<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">

<!-- This custom style allows for wrapping within text in /pre/ tags -->
<style>
pre {
    white-space: pre-wrap;       /* CSS 3 */
    white-space: -moz-pre-wrap;  /* Mozilla, since 1999 */
    white-space: -pre-wrap;      /* Opera 4-6 */
    white-space: -o-pre-wrap;    /* Opera 7 */
    word-wrap: break-word;       /* Internet Explorer 5.5+ */
    font-family: 'Courier New', 'Courier';
    font-size: medium;
}

typewriter {
	font-family: 'Courier New', 'Courier';
}
</style>

<html>
<head>
<title>Ghidra Server README</title>
</head>
<body>

<h1 align="center">Ghidra Server README</h1>

<h2>Table of Contents</h2>
<UL>
  <LI><a href="#introduction">Introduction</a></LI>
  <LI><a href="#javaRuntime">Java Runtime Environment</a></LI>
  <LI><a href="#serverConfig">Server Configuration</a></LI>
  <LI><a href="#serverLogs">Server Logs</a></LI>
  <LI><a href="#serverMemory">Server Memory Considerations</a></LI>
  <LI><a href="#dnsNote">Note regarding use of DNS (name lookup service)</a></LI>
  <LI><a href="#userAuthentication">User Authentication</a></LI>
  <LI><a href="#sshAuthentication">SSH User Authentication</a></LI>
  <LI><a href="#serverOptions">Server Options</a></LI>
  <LI><a href="#running_windows">Running Ghidra Server on Microsoft Windows</a></LI>
  <UL>
    <LI><a href="#windows_scripts">Server Scripts</a></LI>
    <LI><a href="#windows_console">Running Server in Console Window</a></LI>
    <LI><a href="#windows_install">Install as Automatic Service</a></LI>
	<LI><a href="#windows_uninstall">Uninstall Service</a></LI>
  </UL>
  <LI><a href="#running_linux_mac">Running Ghidra Server on Linux or macOS</a></LI>
  <UL>
	<LI><a href="#linux_mac_scripts">Server Scripts</a></LI>
  	<LI><a href="#linux_mac_console">Running Server in Console Window</a></LI>
  	<LI><a href="#linux_mac_install">Install as Automatic Service</a></LI>
	<LI><a href="#linux_mac_uninstall">Uninstall Service</a></LI>
  </UL>
  <LI><a href="#serverAdministration">Server Administration</a></LI>
  <LI><a href="#repositoryBackup">Repository Backup</a></LI>
  <LI><a href="#obsoleteCheckouts">Clearing Obsolete Checkouts</a></LI>
  <LI><a href="#pkiCertificates">PKI Certificates</a></LI>
  <LI><a href="#pkiCertificateAuthorities">Managing PKI Certificate Authorities</a></LI>
  <LI><a href="#upgradeServer">Upgrading the Ghidra Server Installation</a></LI>
  <LI><a href="#troubleshooting">Troubleshooting / Known Issues</a></LI>
  <UL>
   	<LI><a href="#checkinFailures">Failures Creating Repository Folders / Checking in Files</a></LI>
   	<LI><a href="#connectErrors">Client/Server connection errors</a></LI>
	<LI><a href="#windowsMissingTempDirectory">MS Windows - ERROR Missing Temp Directory</a></LI>
	<LI><a href="#windows7and8_scriptErrors">MS Windows 7 and 8 - ghidraSvr.bat, svrInstall.bat, 
	or svrUninstall.bat Error</a></LI>
	<LI><a href="#selinuxDisabled">Linux - SELinux must be disabled</a></LI>
	<LI><a href="#randomHang">Linux - Potential hang from /dev/random depletion</a></LI>
	<LI><a href="#macDiskAccess">macOS - Service fails to start</a></LI>
  </UL>
</UL>

<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>

<h2><a name="introduction">Introduction</a></h2>

<P>
The Ghidra Server is incorporated into the standard Ghidra software distribution. Simply unpack the 
Ghidra distribution, configure the Ghidra Server and perform the OS-specific install and you should 
have the server running in no time.
</P>

<P>
The Ghidra Server utilizes the YAJSW Java service wrapper to launch the application and provides OS 
specific scripts which enable the application to run as a service.
</P>

<P>
<b>NOTE</b>: It is very important that only a single server instance is running against any given 
server repositories directory.  This can be assured if only the default port is ever used.  
The daemon/service mechanism assumes that only one instance of the service exists.  Attempting to 
run a second concurrent instance may lead to difficulties and is not supported.
</P>

<P>
<b>NOTE</b>: It is highly recommended that the installation files for Ghidra reside on a local drive 
and that the intended Ghidra Server process owner is granted full access to the Ghidra installation 
directory (this is frequently not the case for NFS/SMB mounted home directories). 
</P>

<P>
<b>NOTE</b>: It is highly recommended that you establish a repositories directory outside of your 
Ghidra installation directory so that it may be re-used more easily with future upgraded 
installations of Ghidra.
</P>  

<P>
You may also refer to the <typewriter>InstallationGuide.html</typewriter> file within the 
<typewriter>docs</typewriter> subdirectory for general installation information.
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="javaRuntime">Java Runtime Environment</a></h2>
<P>
The installation of a suitable Java Runtime Environment must be completed before installing or
running the Ghidra Server.  Please refer to the Ghidra Installation Guide to identify 
a suitable version.  Since the Ghidra Server is unable to interactively identify a Java installation
at runtime it must rely upon the setting of JAVA_HOME, execution search PATH or the use of standard 
Java installation locations.  It is important to consider the service execution environment which may 
differ from the administrator who may be installing the service.  For this reason use of an installed 
Java release may be preferable over one that is simply unpacked to an arbitrary location.
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="serverConfig">Server Configuration</a></h2>
<P>
Before installing and running the Ghidra Server, the <typewriter>server/server.conf</typewriter> 
file must be modified to suit your particular needs.  Within this file, locate the lines labeled:
<PRE>
    wrapper.app.parameter.#
</PRE>
These lines correspond to a sequential list of server command line arguments - be sure not duplicate 
a parameter number.  The comments within this file indicate the available command line arguments 
which should be specified here based upon the desired user authentication, repositories directory 
location and other associated options.
</P>

<P>
You should generally avoid using the default repositories location and specify a location outside 
your installation directory using an absolute path specification.
</P>
  
<P>
When upgrading your Ghidra installation, you will need to copy your app parameters from your old 
<typewriter>server.conf</typewriter> to the new <typewriter>server.conf</typewriter>.  Do not copy 
the entire <typewriter>server.conf</typewriter> file as this may prevent the server from running 
properly.  If running as a service, you must run the <typewriter>server/svrUninstall</typewriter> script 
from the old installation before running the <typewriter>server/svrInstall</typewriter> script from the 
new installation.  Using a non-default repositories directory outside your Ghidra installation
will simplify the migration process.
</P> 

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="serverLog">Server Logs</a></h2>

<P>The Ghidra Server produces two log files, which for the most part have the same content.
The service <i>wrapper.log</i> file generally resides within the Ghidra installation root 
directory, while the <i>server.log</i> file resides within the configured <i>repositories</i> 
directory.  When running the server in console mode all <i>wrapper.log</i> output is directed
to the console.

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="serverMemory">Server Memory Considerations</a></h2>

<P>
The Ghidra Server currently maintains an in-memory state for all repositories. We are aware that 
this can limit the scalability of the Ghidra Server.  The maximum memory used by the process can be 
set within the <typewriter>server/server.conf</typewriter> file by adjusting the following setting:
<PRE>
    wrapper.java.maxmemory
</PRE>
</P>

<P>
<b>WARNING</b>! There are currently no safeguards when insufficient memory is available to the Ghidra 
Server and can cause severe failure if an out of memory error occurs.
</P>

<P>
The following formula can be used to approximate an appropriate setting for this 
<typewriter>maxmemory</typewriter> value where <typewriter>FileCount</typewriter> 
represents the maximum number of repository files and <typewriter>ClientCount</typewriter> 
is the number of active Ghidra clients connected at one time.
<PRE>
    wrapper.java.maxmemory = 16 + (32 * FileCount/10000) + (2 * ClientCount)
</PRE>
Example:
<PRE>
    100,000 files and 25 connected Ghidra clients
    16 + (32 * 100000/10000) + (2 * 25) = 386
    wrapper.java.maxmemory=772    <i>(2 * 386, see NOTE below)</i>
</PRE>
</P>
<P>
NOTE: Due to the dynamic memory demands on the server not considered by this calculation (e.g., open file handles, etc.), 
the actual <i>maxmemory</i> setting used should be larger
than the calculated value.  At a minimum, it is recommended that the calculated value be doubled, and a larger value
may be appropriate based upon server loading.</P>
<P>
The Java VisualVM tool (if available for your host) may also be used to examine memory usage while 
the server is running.  This tool is NOT provided with any Ghidra distribution.
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="dnsNote">Note regarding use of DNS (name lookup service)</a></h2>

<P>
Both Ghidra Server and client application make extensive use of forward and reverse network name 
lookups.  If this service is not properly configured on your network and hosts, names may fail to 
be resolved or in certain cases cause severe performance delays due to improperly serviced DNS 
name/address queries.
</P>

<P>
By default the server will attempt to identify an appropriate remote access IPv4 address which will
be written to the log at startup.  In addition, the server will listen for incoming 
connections on all IPv4 interfaces by default.  It is important to understand the difference between 
the published remote access address and the listening address (i.e. interface) which are both
configurable.  See the <typewriter>-ip</typewriter> and <typewriter>-i</typewriter> options in 
the <a href="#serverOptions">Server Options</a> section for more details.
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="userAuthentication">User Authentication</a></h2>

<P>
The Ghidra Server has been designed to support many  possible user authentication modes:

<UL>
	<LI><u>No authentication</u> - any user which has been added to the server may connect without 
	password or credentials.</LI>
	<br>
	<LI><u>Local Ghidra password (<typewriter>-a0</typewriter>)</u> - passwords associated with 
	each user added to the server are maintained in the <typewriter>users</typewriter> file located 
	within the repositories directory. The user will be prompted for this password when connecting 
	to the server.  The default password <typewriter>changeme</typewriter> is used when a user is 
	first added or when the user is reset (see <a href="#serverAdministration">Server 
	Administration</a>).  This default password must be changed by the user to avoid its expiration.</LI>
	<br>
	<LI><u>Active Directory via Kerberos (<typewriter>-a1</typewriter>)</u> - user authentication is
	performed against your local Active Directory system using Kerberos to do so.  The -d&lt;ad_domain&gt;
	argument is required to specify the domain name of your Active Directory system.
	<p>
	It is also possible to authenticate against your Active Directory system using LDAP.  See the
	LDAP example when using JAAS -a4 mode.
	</LI>
	<br> 
	<LI><u>PKI authentication (<typewriter>-a2</typewriter>)</u> - user authentication is performed 
	using PKI user certificates.  When using this mode, the distinguished name (DN) for each user 
	must be	associated with each server User ID (see <a href="#serverAdministration">Server 
	Administration</a>).  In addition, each user must configure Ghidra with the location of their 
	signing key/certificate keystore file (see <a href="#pkiCertificates">PKI Certificates</a> 
	for more information). 
	<p>
	Please note that each user&apos;s certificate must be issued by a trusted certificate authority 
	which has been properly added to the Ghidra Server&apos;s <typewriter>cacerts</typewriter> file.  See 
	<a href="#pkiCertificateAuthorities">Managing PKI Certificate Authorities</a> for more information.
	<p>
    In an attempt to simplify the determination of user DN&apos;s, a log file 
    (<typewriter>UnknownDN.log</typewriter>) records user DNs which are unknown.  After adding a 
    user to the server, ask the user to attempt a login using their PKCS certificate.  This should 
    result in their DN being recorded to this log file.  The server administrator may now copy the 
    appropriate DN from this log file when assigning the DN for a user.
	</LI>
    <br>
	<LI><u>JAAS - Java Authentication and Authorization Service (<typewriter>-a4</typewriter>)</u> - 
	user authentication is delegated to the JAAS subsystem.  The -jaas &lt;config_file&gt; argument
	is required to specify the JAAS config file.  The JAAS config file supplied (<i>server/jaas.conf</i>)
	contains various example configurations which may be used to establish an 'auth' configuration 
	section.  None of the example configurations use the 'auth' name so they will be ignored by default.
	<p>
	JAAS is architected similar to Linux/Unix PAM, where a named authentication configuration is possibly
	composed of several different modules.  Ghidra's support of JAAS only handles single simple
	JAAS modules that requests the name and password from the user.
	<p>
	Some known JAAS login modules:
	<ul>
		<li><u>com.sun.security.auth.module.LdapLoginModule</u> - allows authentication to an LDAP server.  There
		is an example of using this module to authenticate against an Active Directory system in the
		jaas.conf file.
		</li>
		<li><u>net.sf.jpam.jaas.JpamLoginModule</u> - (Linux/Unix server only) allows authentication against
		the local PAM configuration.  You will need to download JPAM from SourceForce and install the
		libraries in the necessary locations.  See the example in the <i>jaas.conf</i> file. 
		</li>
		<li><u>ghidra.server.security.loginmodule.ExternalProgramLoginModule</u> - spawns an external
		program for each authentication request, and uses the external program's exit code as the indicator
		of successful authentication.
		<p>
		There is an example (and non-useful) implementation of an external authenticator provided with
		the Ghidra instalation called <i>server/jaas_external_program.example.sh</i>.
		<p>
		This login module strives to be compatible with Apache's mod_authnz_external API, and you should
		be able to use any mod_authnz_external authenticator with Ghidra.
		<p>
		The external program is fed the username\n and password\n on its STDIN (ie. two text lines).
		The external authenticator needs to exit with 0 (zero) error level
 		if the authentication was successful, or a non-zero error level if not successful.
		</li>
		<li><u>com.sun.security.auth.module.Krb5LoginModule</u> - not recommended - this login module
		is used in the -a1 Active Directory via Kerberos authentication mode, and as such you should use it that way.  
		</li>
	</ul> 
	
	</LI>
	<br>
	<LI><u>Use of an SSH pre-shared key (<typewriter>-ssh</typewriter>)</u> is supported as an 
	alternate form of authentication when using Local Ghidra password (<typewriter>-a0</typewriter>).
	This SSH authentication is currently supported by the Headless Analyzer only.  See 
	<a href="#sshAuthentication">SSH User Authentication</a> for configuration details.</LI>
</UL>       
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="sshAuthentication">SSH User Authentication</a></h2>

<P>
When the <typewriter>-ssh</typewriter> option has been included in conjunction with password based 
authentications mode (<typewriter>-a0</typewriter> a user's SSH public key may be added to the server to facilitate 
access by a Headless Analyzer.  An SSH public key file must be added to the server repository for 
each user who requires headless SSH authentication.  The SSH public key file (e.g., 
<typewriter>id_rsa.pub</typewriter>) must be copied to the <typewriter>repositories/~ssh</typewriter> 
subdirectory to a file named <typewriter>&lt;username&gt;.pub</typewriter>.  Removing the file will 
eliminate SSH based authentication for the corresponding user.  When creating the 
<typewriter>~ssh</typewriter> subdirectory, it should be owned by the Ghidra Server process 
owner with full access and any SSH public keys readable by the process owner.  Changes to the SSH 
public key files may be made without restarting the Ghidra Server.
</P>
<P>Each user may generate a suitable SSH key pair with the <typewriter>ssh-keygen</typewriter> command issued from a
shell prompt.  A PEM formatted RSA key-pair should be generated using the following command options:
</P>
<PRE>
   ssh-keygen -m pem -t rsa -b 2048
</PRE>
<P>NOTE: Ghidra Server authentication does not currently support the OPENSSH key format which may be the default 
<typewriter>ssh-keygen</typewriter> format (<typewriter>-m</typewriter> option) on some systems such as Ubuntu.  
In addition, other key types (<typewriter>-t</typewriter> option) such as <i>ecdsa</i> and <i>ed25519</i> 
are not currently supported.
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="serverOptions">Server Options</a></h2>

<UL>
	<LI>Networking options
		<UL>
			<LI><typewriter>-ip &lt;hostname&gt;</typewriter><br>Identifies the remote access hostname (FQDN) 
			or IPv4 address which should be used by remote clients to access the server.  By default the 
			host name reported by the operating system is resolved to an IPv4 address, if this fails the 
			local loopback address is used.  The server log will indicate the remote access hostname 
			at startup.  This option may be required when a server has multiple IP interfaces, relies on 
			a dynamic DNS or other network address translation for incoming connections.
			This option establishes the property value for <i>java.rmi.server.hostname</i>.
			</LI>
			<br>
			<LI><typewriter>-i &lt;#.#.#.#&gt;</typewriter><br>Forces the server to be bound to a specific 
			IPv4 interface on the server.  If specified and the <typewriter>-ip</typewriter> option is not, 
			the address specified by <typewriter>-i</typewriter> will establish the remote access IP 
			address as well as restrict the listening interface. If this option is not specified connections 
			will be accepted on any interface.</LI>
			<br>
			<LI><typewriter>-p#</typewriter><br>Allows the base TCP port to be specified (default: 13100).  The 
			server utilizes three (3) TCP ports starting with the specified base port (e.g., 13100,13101 and 13102).
			The ports utilized are logged by the server during startup.</LI>
			<br>
			<LI><typewriter>-n</typewriter><br>Enables reverse name lookup for IP addresses when logging 
			(requires proper configuration of reverse lookup by your DNS server).  Please note that logging 
			of host names is now disabled by default due to the slow-down which occurs when reverse DNS is 
			not properly configured on the network.</LI>
		</UL>
	</LI>
	<br>
	<LI>Authentication options
		<UL>
			<LI><typewriter>-a#</typewriter><br>Allows a user authentication mode to be specified (see 
			<a href=#userAuthentication>User Authentication</a>)</LI>
			<br>
			<LI><typewriter>-d&lt;ad_domain&gt;</typewriter><br>Sets the Active Directory domain name.
			Example: "-dmydomain.com"</LI>
			<br>
			<LI><typewriter>-e#</typewriter><br>Allows the reset password expiration to be set to a 
			specified number of days (default is 1-day).  A value of 0 prevents expiration.</LI>
			<br>
			<LI><typewriter>-jaas &lt;config_file&gt;</typewriter><br>Specifies the path to the JAAS
			config file (when using -a4), relative to the ghidra/server directory (if not absolute).
			<p>
			See jaas.conf for examples and suggestions. It is the system administrator's 
			responsibility to craft their own JAAS configuration directive when using the -a4 mode.</LI>
			<br>
			<LI><typewriter>-u</typewriter><br>Allows the server login user ID to be specified at time of 
			login for <typewriter>-a0</typewriter> authentication mode.  Without this option, the users 
			client-side login ID will be assumed.</LI>
			<br>
			<LI><typewriter>-autoProvision</typewriter><br>Enable the auto-creation of new Ghidra Server
			users when they successfully authenticate to the server (-a1 and -a4 modes only).
			Users removed from the authentication provider (e.g., Active Directory) will need to be
			deleted manually from the Ghidra Server using svrAdmin command.</LI>
			<br>
			<LI><typewriter>-anonymous</typewriter><br>Enable anonymous access support for Ghidra Server 
			and its repositories.  Only those repositories which specifically enable anonymous access will be 
			accessible as read-only to an anonymous user.</LI>
			<br>
			<LI><typewriter>-ssh</typewriter><br>Enable SSH as an alternate form of authentication when 
			using <typewriter>-a0</typewriter> authentication mode.</LI>
			<br>
		</UL>
	</LI>
</UL>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="running_windows">Running Ghidra Server on Microsoft Windows</a></h2>

<a name="windows_scripts"><h3><u>Server Scripts (located within the server subdirectory)</u></h3></a>
<UL>
	<LI><typewriter>svrInstall.bat</typewriter><br>installs server as service (<typewriter>ghidraSvr</typewriter>)</LI>
	<br>
	<LI><typewriter>svrUninstall.bat</typewriter><br>removes previously installed server service</LI>
	<br>
	<LI><typewriter>svrAdmin.bat</typewriter><br>facilitates Ghidra Server administrative commands 
	(see <a href="#serverAdministration">Server Administration</a>)</LI>
	<br>
	<LI><typewriter>ghidraSvr.bat</typewriter><br>provides a variety of commands for controlling 
	the server when	running as a daemon process.  When running this script it accepts a single 
	argument which is one of the following commands.  Many of these commands are included so that 
	this script may be used for controlling the service.</LI>
	<UL>
		<LI><typewriter>console</typewriter><br>starts server within the current terminal window.  
		<typewriter>console</typewriter> argument may be omitted to allow for double-click execution 
		in this mode.</LI>
		<br>
		<LI><typewriter>start</typewriter><br>starts the previously installed Ghidra Server service</LI>
		<br>
		<LI><typewriter>stop</typewriter><br>stops the installed Ghidra Server service which is 
		currently running</LI>
		<br>
		<LI><typewriter>restart</typewriter><br>stops and restarts the previously installed Ghidra 
		Server service</LI>
		<br>
		<LI><typewriter>status</typewriter><br>displays the current status of the Ghidra Server 
		(<typewriter>ghidraSvr</typewriter>) service</LI>
	</UL>
    <br>
    <b>NOTE</b>: The above scripts may be run from a <typewriter>CMD</typewriter> window, or by 
    double-clicking the script file from an Explorer window.  Other than the console and status 
    operation, elevated privilege is needed to run these commands.  As such the user executing 
    these scripts must be a member of the Administrator group and must be run with elevated privilege.  
    If using Windows Vista or newer, the best way to accomplish this is to run the 
    <typewriter>CMD</typewriter> shell using the <typewriter>Run as Administrator</typewriter>
    action which is available by right-clicking on a command shortcut or batch file.  If the 
    <typewriter>CMD</typewriter> shell is run in this manner, the Ghidra Server scripts may then be 
    executed within the shell to run with administrator privilege.
</UL>

<br>
<a name="windows_console"><h3><u>Running Server in Console Window (intended for diagnostic use only)</u></h3></a>
<P>
    <b>NOTE</b>: Starting the server in console mode is generally intended for diagnostic use only.  
    Extreme care must be taken to ensure that any user who starts the Ghidra Server via this script 
    has full access to all directories and files within the root repository directory.
    <br><br>
    If the Ghidra Server is not already running, it may be started within a console window by 
    running the <typewriter>ghidraSvr.bat console</typewriter> command.  When you wish to terminate the 
    server, use the <typewriter>Ctrl-C</typewriter> key sequence within the server console window and
    wait for a clean shutdown.
</P>

<br>
<a name="windows_install"><h3><u>Install as Automatic Service (<B>must have Administrator privilege</B>)</u></h3></a>
<P>
    The Ghidra Server may be installed as an automatic service by executing the 
    <typewriter>svrInstall.bat</typewriter> script.  This script may be run from a 
    <typewriter>CMD</typewriter> window, or by double-clicking the script file from an Explorer 
    window.  Once installed, the server will start automatically when the system is booted.  
    Immediately after running this script the service will not be running, you will need to either 
    reboot or start the service from the Service Control Panel.
</P>

<br>
<a name="windows_uninstall"><h3><u>Uninstall Service (<B>must have Administrator privilege</B>)</u></h3></a>
<P>
    If after installing the Ghidra Server as a service you wish to uninstall it, you may run the 
    <typewriter>svrUninstall.bat</typewriter> script.  You must stop the service via the Service 
    Control Panel prior to running this script.  This script may be run from a <typewriter>CMD</typewriter>
    window, or by double-clicking the script file from an Explorer window.  
</P>
<P>
    <b>NOTE</b>: It is very important that you uninstall the service prior to doing any of the 
    following activities:
	<UL>
		<LI>deleting or upgrading the Ghidra installation</LI>
		<LI>moving/renaming the Ghidra installation directory</LI>
	</UL>
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="running_linux_mac">Running Ghidra Server on Linux or macOS</a></h2>

<B>NOTE:</B> macOS has limited support (see <a href="#macDiskAccess">macOS - Service fails to start</a>).</u>

<a name="linux_mac_scripts"><h3><u>Server Scripts (located within the server subdirectory)</u></h3></a>

<UL>
	<LI><typewriter>svrInstall</typewriter><br>installs server as service (<typewriter>ghidraSvr</typewriter> 
	or <typewriter>wrapper.ghidraSvr</typewriter>)</LI>
	<br>
	<LI><typewriter>svrUninstall</typewriter><br>removes previously installed server service</LI>
	<br>
	<LI><typewriter>svrAdmin</typewriter><br>facilitates administrative commands (see 
	<a href="#serverAdministration">Server Administration)</a></LI>
	<br>
	<LI><typewriter>ghidraSvr</typewriter><br>provides a variety of commands for controlling the 
	server when running as a daemon process.  When running this script it accepts a single argument 
	which is one of the following commands.  Many of these commands are included so that this script 
	may be used for	controlling the service.</LI>
	<br>
	<LI><typewriter>console</typewriter><br>starts server within the current terminal window</LI>
	<br>
	<LI><typewriter>start</typewriter><br>starts the previously installed Ghidra Server service</LI>
	<br>
	<LI><typewriter>stop</typewriter><br>stops the installed Ghidra Server service which is 
	currently running</LI>
	<br>
	<LI><typewriter>restart</typewriter><br>stops and restarts the previously installed Ghidra 
	Server service</LI>
	<br>
	<LI><typewriter>status</typewriter><br>displays the current status of the Ghidra Server 
	(<typewriter>ghidraSvr</typewriter>) service</LI>
</UL>

<br>
<a name="linux_mac_console"><h3><u>Running Server in Console Window</u></h3></a>
<P>
	<b>NOTE</b>: Starting the server in console mode is generally intended for diagnostic use 
	only. Care must be taken to ensure that any user who starts the Ghidra Server via this script 
    has full access to all directories and files within the root repository directory.
</P>
<P>
    If the Ghidra Server is not already running, it may be started within a terminal window by 
    running the command: <typewriter>ghidraSvr console</typewriter>.  When you wish to terminate 
    the server, use the <typewriter>Ctrl-C</typewriter> key sequence within the server console window and
    wait for a clean shutdown.
</P>

<br>
<a name="linux_mac_install"><h3><u>Install as Automatic Service (must have admin privilege)</u></h3></a>
<P>
	The Ghidra Server may be installed as an automatic service by executing the 
	<typewriter>svrInstall</typewriter> script.  Once installed, the server will start automatically 
	when the system is booted.
</P>
<P>
	If it is preferred to run the service with a dedicated local user account, the following 
	entry may be added to the <i>server.conf</i> file with the appropriate account specified in
	place of &lt;uid&gt;.
	A dedicated local service account should generally be a no-login account with a 
	corresponding group identifier with the same name (i.e., see /etc/passwd and /etc/group).
	The local account should be established and specified with server.conf prior to
	installation of the Ghidra Server service. 
</P>
<PRE>
	wrapper.app.account=&lt;uid&gt;
</PRE>
<P>
It is also important that the repositories directory and Ghidra installation files 
be owned by the service account with proper permissions.  Note that while the Ghidra Server
Java process will run using the specified <i>uid</i> the <i>wrapper</i> process will continue 
to run as <i>root</i> and monitor/manage the Java process.
</P> 
<br>
<a name="linux_mac_uninstall"><h3><u>Uninstall Service (must have admin privilege)</u></h3></a>
<P>
	If after installing the Ghidra Server as a service you wish to uninstall it, you may run the 
	<typewriter>svrUninstall</typewriter> script.
</P>
<P>
	<b>NOTE</b>: It is very important that you uninstall the service prior to doing any of the following 
	activities:

	<UL>
		<LI>deleting or upgrading the Ghidra installation</LI>
		<LI>moving/renaming the Ghidra installation directory</LI>
	</UL>
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="serverAdministration">Server Administration</a></h2>

<P>
    The script <typewriter>svrAdmin</typewriter>, or <typewriter>svrAdmin.bat</typewriter>, provides 
    the ability to manage Ghidra Server users and repositories.  This script must be run from a 
    command shell so that the proper command line arguments may be specified.  This command
    should only be used after the corresponding Ghidra installation has been properly 
    configured via modification of the <typewriter>server/server.conf</typewriter> file
    (see <a href="#serverConfig">Server Configuration</a>) and installed and/or started.  
</P><P>
    Many of the commands are queued for subsequent execution by the Ghidra Server process.
    Due to this queing, there may be a delay between the invocation of a <typewriter>svrAdmin</typewriter>
    command and its desired affect.  The Ghidra log file(s) may be examined for feedback on 
    queued command execution (see <a href="#serverLogs">Server Logs</a>).
</P>

<P>
    The general command usage is:

    <PRE>
    svrAdmin [&lt;server-root-path&gt;]
             [-add &lt;user_sid&gt; [--p]]
             [-grant &lt;user_sid&gt; &lt;"+r"|"+w"|"+a"&gt; &lt;repository_name&gt;] 
             [-revoke &lt;user_sid&gt; &lt;repository_name&gt;] 
             [-remove &lt;user_sid&gt;] 
             [-reset &lt;user_sid&gt; [--p]] 
             [-dn &lt;user_sid&gt; &quot;&lt;user_dn&gt;&quot;]
             [-list  &lt;user_sid&gt; [&lt;user_sid&gt;...]]
             [-list [--users]]
             [-users]
             [-migrate-all]
             [-migrate &quot;&lt;repository_name&gt;&quot;]
    </PRE>
</P>

<UL>
    <LI><typewriter>&lt;server-root-path&gt;</typewriter><br>
    There is normally no need to specify this argument on the command line.
    The default server-root-path is determined by
    the server.conf setting of the 'ghidra.repositories.dir' variable.  This allows both the server
    execution and <typewriter>svrAdmin</typewriter> script to utilize the same setting.
    <br>
    <LI><typewriter>-add</typewriter>&nbsp;&nbsp;<b>(Adding a User)</b><br>
    All authentication modes require that a user first be added to the server for a connection to 
    be permitted.  If Ghidra password authentication is used [<typewriter>-a0</typewriter>], the 
    initial password is set to <typewriter>changeme</typewriter>. This password must be changed by 
    the user within 24-hours to avoid its expiration (password expiration period can be extended as 
    a server option, see <typewriter>-e</typewriter> <a href="#serverOptions">server option</a>).  
    Alternatively, the initial password may be specified by including the optional <typewriter>--p</typewriter>
    parameter which will prompt for an initial password.
    <br><br>
    Examples:
    <PRE>
        svrAdmin -add mySID
        svrAdmin -add mySID --p
    </PRE>
    </LI>
    <LI><typewriter>-grant</typewriter>&nbsp;&nbsp;<b>(Grant Repository Access for User)</b><br>
    Grant access for a specified user and repository where both must be known to the server.
    Repository access permission must be specified as +r for READ_ONLY, +w for WRITE or +a for ADMIN.
    Examples:
    <PRE>
        svrAdmin -grant mySID +a myRepo
        svrAdmin -grant mySID +w myRepo
    </PRE>
    </LI>
    <LI><typewriter>-revoke</typewriter>&nbsp;&nbsp;<b>(Revoke Repository Access for User)</b><br>
    Revoke the access for a specified user and named repository.  Currently, revoking access for a 
    user does not disconnect them if currently connected.
    Examples:
    <PRE>
        svrAdmin -revoke mySID myRepo
    </PRE>
    </LI>
    <LI><typewriter>-remove</typewriter>&nbsp;&nbsp;<b>(Removing a User)</b><br>
    A user may be removed from the Ghidra Server and all repositories with this command form.  This will only prevent the 
    specified user from connecting to the server in the future and will have no effect on the state or history 
    of repository files.  If a repository admin wishes to clear a user&apos;s checkouts, this is 
    a separate task which may be performed from an admin&apos;s Ghidra client.  Currently, removing a 
    user does not disconnect them if currently connected.
    <br><br>
    Example:
    <PRE>
        svrAdmin -remove mySID
    </PRE>
    </LI>
    <LI><typewriter>-reset</typewriter>&nbsp;&nbsp;<b>(Reset User&apos;s Ghidra Password)</b><br>
    If a user&apos;s password has expired, or has simply been forgotten, the password may be reset 
    to <typewriter>changeme</typewriter>.  After resetting, this password must be changed by the user within 
    24-hours to avoid its expiration (password expiration period can be extended as a server option).
    Alternatively, the new password may be specified by including the optional <typewriter>--p</typewriter>
    parameter which will prompt for an initial password.
    <br><br>
    Example:
    <PRE>
        svrAdmin -reset mySID
        svrAdmin -reset mySID --p
    </PRE>
    </LI>
    <LI><typewriter>-dn</typewriter>&nbsp;&nbsp;<b>(Assign User&apos;s Distinguished Name)</b><br>
    The use of PKI authentication requires that each user&apos;s DN be associated with their user SID.
    <br><br>
    Example:
    <PRE>
        svrAdmin -dn mySID &quot;CN=MyName,OU=AGENCY,OU=DoD,O=U.S. Government,C=US&quot;
    </PRE>
    <b>NOTE</b>: After having been added to the server, a user&apos;s DN may be copied from the 
    <typewriter>UnknownDN.log</typewriter> file following an attempted connection with their PKCS 
    certificate.
    </LI>
    <LI><typewriter>-list</typewriter>&nbsp;&nbsp;<b>(List All Repositories and/or User Permissions)</b><br>
    If the <i>--users</i> option is also present, the complete user access
    list will be included for each repository. Otherwise, command may be followed by one or user SIDs (separated by a space)
    which will limit the displayed repository list and access permissions to those users specified.
    <br><br>
    Example:
    <PRE>
        svrAdmin -list
        svrAdmin -list --users
        svrAdmin -list mySID
    </PRE>
    <LI><typewriter>-users</typewriter>&nbsp;&nbsp;<b>(List All Users)</b><br>
    Lists all users with server access.
    <br><br>
    Example:
    <PRE>
        svrAdmin -users
    </PRE>
    </LI>
    <LI><typewriter>-migrate-all</typewriter>&nbsp;&nbsp;<b>(Migrate All Repositories to Use Indexed 
    File-System Storage)</b><br>
    For all repositories which are using the deprecated Mangled Filesystem storage, they will be 
    marked for migration to the Indexed Filesystem storage with support for longer file pathnames.  
    The actual migration will be performed when the Ghidra Server is restarted.
    <br><br>
    Please note that any migration to the Indexed filesystem storage is a one-way conversion so a 
    backup of your server repositories directory is highly recommended before proceeding.
    <br><br>
    Example:
    <PRE>
        svrAdmin -migrate-all
    </PRE>
    </LI>
    <LI><typewriter>-migrate</typewriter>&nbsp;&nbsp;<b>(Migrate a Specified Repository to use 
    Indexed File-System Storage)</b><br>
    The specified repository will be marked for migration to the Indexed Filesystem storage with 
    support for longer file pathnames.  The actual migration will be performed when the Ghidra 
    Server is restarted.
    <br><br>
    Please note that any migration to the Indexed filesystem storage is a one-way conversion so a 
    backup of your server repositories directory is highly recommended before proceeding.
    <br><br>
    Example:
    <PRE>
        svrAdmin -migrate &quot;myProject&quot;
    </PRE>
    </LI>    
</UL>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="repositoryBackup">Repository Backup</a></h2>

<P>
As with any server, it is highly recommended that your server repositories directory be periodically 
backed-up or whenever an upgrade (or data migration) is performed.  While backups may be taken while 
the Ghidra Server is idle (e.g., after midnight), it is always safest to stop the Ghidra Server 
while a backup is in progress.
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="obsoleteCheckouts">Clearing Obsolete Checkouts</a></h2>

<P>
Any user who has Admin privilege of a specific repository may use the Ghidra client to View 
Checkouts for a specific file and Delete individual checkouts from those that are listed.  The 
<typewriter>View Checkouts</typewriter> action is available from the popup-menu of the Ghidra 
Project Window by right-clicking on a specific project file.
</P>

<P>
Under special circumstances (e.g., classroom environment) it may be desirable to remove all 
checkouts either for a specific repository or an entire Ghidra Server.  Under Linux/Mac this is 
most easily accomplished from the command shell while the Ghidra Server is stopped.  The following 
command may be used:

<PRE>
    find &lt;repo-path&gt; -name checkout.dat -exec rm {} \;
</PRE>
	
where <typewriter>&lt;repo-path&gt;</typewriter> is the directory path of a specific named 
repository root, or the parent repositories directory if clearing checkouts for all repositories.
<br><br>
WARNING! Since the <typewriter>find</typewriter> command is recursive, care must be taken when 
specifying the <typewriter>&lt;repo-path&gt;</typewriter> and the other parameters.  If you specify 
the incorrect <typewriter>&lt;repo-path&gt;</typewriter> or omit the correct 
<typewriter>-name</typewriter> argument, you may remove important files without the ability to recover.
</P> 

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="pkiCertificates">PKI Certificates</a></h2>

<P>
	PKI keys/certificates can be used to authenticate clients and/or servers.
	When using the Ghidra Server PKI authentication mode this corresponds to "client authentication"
	which requires the <typewriter>server.conf</typewriter> to specify a <typewriter>cacerts</typewriter> 
	file location and each user client to 
	configure a user signing key/certificate keystore file.  If clients wish to authenticate the server,
	the <typewriter>server.conf</typewriter> must specify a server key/certificate keystore 
	file and each user client must configure
	a <typewriter>cacerts</typewriter> file.  See 
	<a href="#"pkiCertificateAuthorities">Managing PKI Certificate Authorities</a>
	for more information on configuring a <typewriter>cacerts</typewriter> file.
</P>

<P>
	User and server certificates must be acquired through one of many trusted authorities
	identified by the <typewriter>cacerts</typewriter> file installed by the peer system.  Your network support 
	staff should be able to help you acquire a suitable signing key/certificate in the form
	of either a <typewriter>*.p12, *.pks,</typewriter> or <typewriter>*.pfx</typewriter> file.
</P>

<P>
	User's of the Ghidra GUI application can install their key/certificate file via the
	project window menu item <B>Edit->Set PKI Certificate...</B>. The user will be prompted 
	for their keystore password the first time key access is required for a network connection
	after starting the application.
	If using the <typewriter>analyzeHeadless</typewriter> script, see the 
	<typewriter>analyzeHeadlessREADME.html</typewriter> file for details.
</P>

<P>
	If the Ghidra Server will be installing a server certificate, the <typewriter>server.conf</typewriter>
	file should be modified to properly identify the server's key/certificate location (<i>ghidra.keystore</i>) 
	and password (<i>ghidra.password</i>).
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="pkiCertificateAuthorities">Managing PKI Certificate Authorities</a></h2>

<P>
When utilizing PKI authentication for a Ghidra Server a set of certificates for trusted Certificate 
Authorities (CA) must be collected and added to a cacerts keystore file created using the Java 
keytool.  The Java keytool can be found within the Java Development Kit (JDK) provided with 
Ghidra (<typewriter>java/bin/keytool</typewriter>) or any other Java distribution.  The default 
cacerts keystore file location is <typewriter>Ghidra/cacerts</typewriter> 
and is also specified by the <typewriter>ghidra.cacerts</typewriter> property setting within the 
<typewriter>server.conf</typewriter> file.  Uncomment this specification within the 
<typewriter>server.conf</typewriter> file to activate use of the <typewriter>cacerts</typewriter>
for all incoming SSL/TLS connections (i.e., all Ghidra client users must install and employ the
use of their personal PKI signing certificate for both headed and headless use - see 
<a href="#pkiCertificates">PKI Certificates</a>).  Clients can also impose server authentication
for all HTTPS and Ghidra Server connections by creating the <typewriter>cacerts</typewriter> file 
and enabling the <typewriter>ghidra.cacerts</typewriter> 
property setting within the support/launch.sh and/or launch.bat scripts.

</P>

<P>
Individual CA public key certificates should be obtained in a Base64 encoding (see sample below). 
If pasting the encoded certificate into a file, be sure to include an extra blank line after the 
END CERTIFICATE line.
</P>

<P>
Sample Base64 encoded certificate:

<PRE>
-----BEGIN CERTIFICATE-----
laSKCIElkjsudCUDusjSUkjeMSUjAJHDuLQWMCMausALkKXMXOOjSKSUjssjSKAA
ksDSDjLKJHAuemCXXUmxxqjaskuDSYRmxiqgDlakkUSUdhemjASKUakjhuEhxMSD
...
ksJKDwocQwyeEIcbzHtyrSLfoeyGCmvbNLGHpgoruSTYQafzDFTgwjkJHCXVDjdg
KDowiyYTXkcuiwCJXuyqCHpdoORriwwcCWUskucuwHDJskuejdkUWJCUDSjujsUE
-----END CERTIFICATE-----

</PRE>
</P>

<P>
You can inspect the contents of a Base64 encoded certificate file with the following command:

<PRE>
    keytool -printcert -v -file &lt;base64file&gt;
</PRE>
   
where:
<UL>
    <LI><typewriter>&lt;base64file&gt;</typewriter> is the file containing the Base64 encoded CA certificate to be imported.</LI>
</UL>

The Owner common name (CN) displayed by this command should be used as the alias when importing the 
certificate into your cacerts file.
<br><br>
The following command should be used to add a CA certificate to a new or existing cacerts file:

<PRE>
    keytool -import -alias &quot;&lt;caAlias&gt;&quot; -file &lt;base64file&gt; -storetype jks -keystore &lt;cacerts-file&gt;
</PRE>
    
where:
<UL>
    <LI><typewriter>&lt;caAlias&gt;</typewriter> is the name of the CA corresponding to the 
    imported certificate.</LI>
    <LI><typewriter>&lt;base64file&gt;</typewriter> is the file containing the Base64 encoded CA 
    certificate to be imported.</LI>
    <LI><typewriter>&lt;cacerts-file&gt;</typewriter> is the cacerts file to be used by the Ghidra 
    Server (and/or client if needed).</LI>
</UL>
    
The keystore password will be requested and is used to restrict future modifications to the 
<typewriter>cacerts</typewriter> file.
<br><br>
When starting the Ghidra Server with PKI authentication enabled, the CA certificates contained 
within the <typewriter>cacerts</typewriter> file will be dumped to the log with their expiration dates.
</P>

<P>
Please note that the Ghidra Server does not currently support Certificate Revocation Lists (CRLs).
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="upgradeServer">Upgrading the Ghidra Server Installation</a></h2>

<P>
<OL>
    <LI>Be sure to backup your projects and tools to ensure that the new Ghidra installation does 
    not overwrite any of your data. Individual program files upgraded to a newer version of Ghidra 
    can not be opened with an older version.</LI>
    <br>
    <LI>Uninstall an installed Ghidra Server Service by following the <typewriter>Uninstall Service</typewriter> 
    instructions corresponding to your operating system (<a href="#windows_uninstall">Windows</a> 
    or <a href="#linux_mac_uninstall">Linux/macOS</a>).</LI>
    <br>
    <LI>Unzip the new Ghidra distribution to a new installation directory (general unpacking and installation 
    guidelines may be found in <typewriter>ghidra_<I>x.x</I>/docs/InstallationGuide.html</typewriter>).</LI>
	<br>
	<LI>Copy the old <typewriter>repositories</typewriter> directory to the new Ghidra Server 
	installation directory.</LI>
    <br>
    <LI>Copy the <typewriter>wrapper.app.parameter.#</typewriter> lines from your old 
    <typewriter>server/server.conf</typewriter> file to the new installation 
    <typewriter>server/server.conf</typewriter>.  For 5.0 release and earlier, your old 
    <typewriter>server.conf</typewriter> file is located within a platform-specific directory 
    (<typewriter>core/os/&lt;platform&gt;</typewriter>). No other changes should be made to your new 
    <typewriter>server.conf</typewriter> file.
    <br><br>
    <B>Do not replace the new <typewriter>server.conf</typewriter> file with your old 
    <typewriter>server.conf</typewriter> file, as this could cause server problems.</B>
    </LI>
	<br>
	<LI>If desired, install the Ghidra Server Service from the new installation server 
	subdirectory by following the instructions corresponding to your operating system 
	(<a href="#windows_install">Windows</a> or <a href="#linux_mac_install">Linux/macOS</a>).</LI>
</OL>

<P>
<B>WARNING!</B> <B>As of Ghidra 7.0 a new project/server storage implementation, 
<typewriter>Indexed-V1</typewriter>, has been added which is not compatible with older versions of 
Ghidra.</B>  The <typewriter>Indexed-V0</typewriter> filesystem storage allows longer filenames and 
paths to exist within a project, while the <typewriter>V1</typewriter> version expands support to 
facilitate some of the very large project/repository features introduced in Ghidra 7.0. Since the 
legacy storage implementation (<typewriter>Mangled</typewriter>) used by older projects and repositories 
is still supported, conflicting storage behavior may exist between a Ghidra project and its server 
repository for long filename/path support. It is highly recommended that all server repositories and 
associated projects be migrated to the new Indexed storage implementation in a coordinated fashion 
after making a complete backup. All new Ghidra projects will utilize the new Indexed storage 
implementation, so care should taken when creating shared projects with older repositories.
</P>


<P>
<B>NOTE:</B> If using Ghidra 6.0.x, opening a project which uses the newer <typewriter>Indexed-V1</typewriter> 
filesystem may cause the project storage to revert to the older <typewriter>Indexed-V0</typewriter> filesystem.
</P>

<P>
A user may determine which storage implementation is used by a project by viewing the 
<typewriter>Project Info</typewriter> display (via <typewriter>Project</typewriter> -&gt;
<typewriter>View Project Info...</typewriter>). Local projects using the legacy <typewriter>Mangled</typewriter> 
filesystem may be migrated to the new <typewriter>Indexed</typewriter> filesystem via this 
<typewriter>Project Info</typewriter> panel. The status of Ghidra Server repositories storage can be 
determined and flagged for migration via the <typewriter>server/svrAdmin</typewriter> script (described 
in the <a href="#serverAdministration">Server Administration</a> section). Please note that any 
migration to the <typewriter>Indexed</typewriter> filesystem storage is a one-way conversion so a 
backup of your project or server repositories directory is highly recommended before proceeding.
</P>


(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
<h2><a name="troubleshooting">Troubleshooting / Known Issues</a></h2>

<a name="checkinFailures"><h3><u>Failures Creating Repository Folders / Checking in Files</u></h3></a>
<P>
If you see continuous failures to create repository folders or failures to check in files, check 
the disk space on the server or folder permissions. When the server runs out of disk space, it 
cannot create folders or check in files.
</P>
<br>

<a name="connectErrors"><h3><u>Client/Server connection errors</u></h3></a>
<P>
The Ghidra Server has transitioned to using SSL/TLS connections when accessing the server's RMI
registry.  This change in communication protocol can cause unexpected symptoms when attempting to
connect incompatible versions of Ghidra.  When an older incompatible Ghidra client attempts to access a 
newer SSL/TLS enabled Ghidra Server registry, the following connection error will occur:
<PRE>
	non-JRMP server at remote endpoint
</PRE> 

<br>
<a name="windowsMissingTempDirectory"><h3><u>MS Windows - ERROR Missing Temp Directory</u></h3></a>
<P>
Running the Ghidra Server as an installed service under Windows may attempt to use a non-existing 
temporary directory (e.g., <typewriter>C:\Windows\system32\config\systemprofile\AppData\Local\Temp\</typewriter>). 
The work-around for this is to configure the server to use an existing temporary directory 
(e.g., <typewriter>C:\Windows\Temp</typewriter>).  This can be done by editing the 
<typewriter>server.conf</typewriter> file, locate the <typewriter>wrapper.java.additional</typewriter> 
entries and add/uncomment an entry with your temporary directory specified. For example:
<PRE>
    wrapper.java.additional.3=-Djava.io.tmpdir=C:\Windows\Temp
</PRE>
Be sure to use the next unique sequence number for your <typewriter>wrapper.java.additional</typewriter> entry.
</P>

<br>
<a name="windows7and8_scriptErrors"><h3><u>MS Windows 7 and 8 - <typewriter>ghidraSvr.bat</typewriter>, 
	<typewriter>svrInstall.bat</typewriter>, or <typewriter>svrUninstall.bat</typewriter> Error</u></h3></a>
<P>
The following error may occur when attempting to install/uninstall/start/stop/restart the Ghidra 
Server under MS Windows 7 or 8 even if the user is a member of the Administrator group:
<PRE>
    Access denied: please check the user credentials
</PRE>
The user executing these scripts must be a member of the Administrator group and must be run with 
elevated privilege.  The best way to accomplish this is to run the <typewriter>CMD</typewriter> 
shell using the <typewriter>Run as Administrator</typewriter> action which is available by 
right-clicking on a command shortcut or batch file.  If the <typewriter>CMD</typewriter> shell is 
run in this manner, the Ghidra Server scripts may then be executed within the shell to run with 
administrator privilege.  Failure to run the scripts in this manner may cause failure information 
to be hidden from view due to the privilege escalation mechanism.
</P>

<br>
<a name="selinuxDisabled"><h3><u>Linux - SELinux must be disabled</u></h3></a>
<P>
The Ghidra Server may not start properly if SELinux has not been disabled.  This setting is 
specified in the file <typewriter>/etc/selinux/config</typewriter>.
</P>

<br>
<a name="randomHang"><h3><u>Linux - Potential hang from /dev/random depletion</u></h3></a>
<P>
SSL communications and the PKI/SSH authentication mechanisms employed by GHIDRA make use of the Java SecureRandom 
class to generate random numbers required by various cryptographic techniques.  On Linux
systems this class makes use of /dev/random to produce these random numbers which in turn
relies on other system entropy sources to feed it.  We have seen that /dev/random can 
become depleted which can cause the dependent Java application to hang.  While Java claims
to have settings which should allow /dev/urandom to be used, these security settings do 
not appear to work as intended.  The best workaround we have found for systems which exhibit
this problem is to install <i>haveged</i> (HArdware Volatile Entropy Gathering and
Expansion Daemon) which will satisfy the entropy demand needed by /dev/random.
</P>

<br>
<a name="macDiskAccess"><h3><u>macOS - Service fails to start</u></h3></a>
<P>
The installed service may fail to start with macOS Mojave (10.14) to macOS Monterey (12.0) due
to changes in the macOS system protection feature.  When the service fails to start it does not
provide any error or logging to help determine the cause.  Although granting <i>Full Disk Access</i> 
to <i>Java</i> can be a workaround, this is rather drastic and is not considered desirable 
since it will allow any Java application to run as root.  Newer versions of macOS (Ventura 13.0 and
later) do not exhibit this issue.
</P>

(<a href="#top">Back to Top</a>)
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>

</body>
</html>
